GEORGE Source Code Information Engine
Thank you for your interest in GEORGE, crowned 1995 Product of the Year, Best Documentation Tool!
GEORGE is a very powerful and versatile tool which can easily be put to use to improve your documentation, informal reuse, information sharing, standards compliance, code visibility, management reviews, code reviews, code delivery, quality audits, code audits, coding conventions, maintenance, code comprehension, code interrogation, code browsing and more!
The following product review was published in the November issue of the X Advisor (www.unx.com) and written by Steven Mikes, Editor-in-Chief. The product review covered the then-current version of GEORGE; the new release 3.0 supports Windows NT and Windows 95 in addition to SunOS, Solaris and HP-UX. The key features of 3.0 include a Wizard-sytle user interface where the developer can select the desired formats from a list of samples (this was a suggestion for enhancement by the author of this article) thus making the tool that much easier to use!
For more information and to request your own evaluation copy, please contact QualSoft at 800-814-6899, 415-494-6100, info@qsoft.com or http://www.qsoft.com.
GEORGE
QualSoft Corporation
If you are a programmer, then you have most certainly been faced with the sometimes daunting task of developing documentation for your program, or even worse - that of others. In fact, it has often been my experience that the documentation part of many software development projects is usually left until last and is rarely developed up front. Oh, yes, there are some developers who go to the bother of producing the program documentation early in the development cycle, but that is usually very limited in its scope and certainly subject to change from what actually gets produced. Even worse, this is only formal documentation and does nothing to provide the reader with deep and accurate insights as to what lies within the actual code.
To compound the problem, once the documentation has been produced, it has to somehow be kept current, accurately reflecting every little change that has been added between releases. And really good documentation of modern object-oriented GUI applications should also contain object hierarchies of the logical and GUI components within the application. This last requirement often demands people with advanced programming and documentation skills (very rare and very expensive) as well as very expensive CASE tools which are usually either too cryptic or complex for the average person to use without re-education in computer software development methodologies that lend themselves to the CASE tool. So what is to be done?
Fear not, we've found the answer -- a new product called GEORGE. (Uh, your guess is as good as anyone's about why it is called this.)
GEORGE is a very simple and powerful automated program documentation generator that just about anyone can use within just a few minutes. This product not only produces highly detailed program documentation (which, by the way, can easily be tailored to conform to existing in-house documentation standards) complete with extensive hypertext sensitive cross-reference indexes, but it does this with amazing speed, computer precise accuracy and standardized formats. The best is that the output is then suitable for PostScript printing, conversion to HTML to be viewed by any World Wide Web browser, such as Mosaic and Netscape; or it can be ported to the Rich Text Format for Word6 and other MS Windows document processors, as well as FrameMaker 4 (and later) and Interleaf.
No, not Stephanopolous, GEORGE -- the new product you can't afford to be without if you are a professional programmer. GEORGE works on a very simple principle: it analyzes your source code, and any other code it refers to (ad infinitum) and proceeds to produce detailed documentation about it in a format you have absolute control over. First, we'll take an overview look at GEORGE and then explain how it works.
GEORGE works by executing a series of scanning and analysis steps, combined with your sources, document definitions and document templates, to produce the final result: a finished document that can be viewed online as FrameMaker and/or Interleaf native documents, or as an HTML document you can view with Mosaic, Netscape or any other WWW browser. You can also produce output suitable for use with Microsoft Word 6 and any other word/documentation processing system capable of interpreting the Rich Text Format (RTF). Figure 1 below illustrates the work flow for GEORGE:
| Xgeorge | an X client to construct new documents |
| GEORGEViewer | extensions to hypertext facilities for FrameMaker and Interleaf |
| GEORGEMerge | used to merge user additions to updated documents (Frame & Interleaf) |
Xgeorge is an X client used to actually create the program documentation, this is the GUI which is the heart of the package. Xgeorge uses 4 editors to scan, analyze and document your C or C++ source code:
The Project Editor is used to define new projects by telling GEORGE the names of the files comprising your source code which you wish to document. You do this by either loading in each file individually, or more likely, by specifying the Makefile which contains the sources and targets you want to build.
The Project Editor automatically loads source files and compiler directives & switches using its Makefile Reader. (GEORGE also has the added advantage of optionally automatically documenting your Makefile and project construction methods as well as the program documentation!) With the Project Editor, you also specify comment positioning conventions specific to your requirements.
Finally, the Project Editor also scans/parses the source modules to see what is in them and produces a preliminary report for you to examine before the final document is produced.
The Selection Editor is then used to accept or reject classes defined within source files. This means you can selectively determine which classes are to be included in the document as well as which are to be explicitly excluded, used mainly to limit the size of the document that will be produced. For example, you may not wish to document every single object or class, or decide to limit the scope of how far down the inclusion path GEORGE will document.
The Document Structure Editor is used to define the layout and formatting style of your final document. Here you define the page layout, fonts and heads, the overall style of your document's final appearance, as well as what information is included within each class GEORGE encounters in the code and what exactly will be the content of the documentation GEORGE will produce for that class. The Document Structure Editor is sort of like the paragraph tagging dialog of FrameMaker, though far more sophisticated because it also deals with the style of the actual content as well as its appearance.
One of the most useful and powerful features of GEORGE is its ability to extract programmer comments from within the source code, combined with the ability for you to associate those comments with specific code items. You can produce detailed output that includes the declarations and definitions of code objects as well as commentary to go along with any of these for which the programmer has provided the necessary commentary, as well as extensive cross-referenced index pages, complete with hypertext links to the actual objects they reference.
In addition, you can also create your own specific descriptive text passages that can be associated to any of the various code objects, in the event the code does not contain the necessary commentary.
There are also a number of very useful substitution variables which can be embedded into the document templates which expand to more useful information when the final documentation is generated.
Finally, you can also create and associate keywords to any part of an item's detail, with a pre-assigned priority level. This also facilitates enforcement of mandatory documentation or comments for particular elements of the source modules.
Since it is impossible to know what your particular documentation style guidelines are in advance, GEORGE comes with a few different basic style sheets which can then be tailored to your specific requirements.
The Error/Warning Editor is used to display the results of the document scanning, analysis and construction phases. You can select any entry in the Editor's list which takes you directly to the associated passage, and directly to the appropriate position within the source code, using the editor of your choice. (The standard UNIX vi editor is the default.)
Once you have created your final document, you may either print it, or view it online. To view it online, depending on what the final output format chosen, you may use GEORGEViewer to read FrameMaker and/or Interleaf documents. For FrameMaker, the output appears as a MIF (Maker Interchange Format) file which GEORGEViewer interprets, including any illustrations and diagrams. This is most useful if you want to maintain online documentation, especially if it contains hypertext links to the source code or other document modules.
When you subsequently make any changes to the documentation, GEORGEMerge can be used to merge those updates into the program documentation automatically when you produce the new document. This is also designed only for use with FrameMaker or Interleaf.
GEORGE also comes with built-in online help of its own. You'll probably want to keep this window handy until you get the hang of it. The GEORGE distribution package is very small, ours contained only the tape, license data sheets, and 1 manual. This is because all of the necessary end-user documentation for GEORGE is already online and accessible from any of the Editor windows.
With GEORGE, you can generate extensive indexes as necessary. GEORGE
comes with a default document template which already defines all major
code objects, except for arguments. If you are using FrameMaker, you can
also take advantage of its built-in hypertext facilities to generate
indexes that are linked directly back to other items in the documentation
or the actual source code. (Using several public domain HTML convertors
available for FrameMaker, you can subsequently convert these into fully
hyper-linked HTML modules.)
The Project Editor allows you to either read in an existing project so you can resume work in progress or make updates to existing GEORGE projects, or you can simply start a new project. When you start new projects, you can either manually import individual source files (if you like doing it the slow way) or you can speed things up considerably by using the automatic import capability by invoking the Makefile Reader.
The Makefile Reader dialog allows you to specify the name of your local 'make' program, the name of the Makefile and any flags you want to set, as well as the various targets you want the documentation pass to apply to. If you want to document everything, the value for the target variable would be 'all'.
An important thing to note is the the Makefile Reader is that it does not interpret your Makefile contents -- instead, it analyses the actual output from an execution of 'make' using your Makefile. This implies that your Makefile should be in a state that produces a clean compilation and link of your source and executables.
You can also set the source module language type. For now, these are limited to:
By default, when GEORGE encounters files ending in .C it sets the source module language type to C++; when it encounters files ending in .c it sets the language type to K&R C.
Once you have defined your project and imported the associated source and header files, the next step is to scan the code. In the Project Editor you select the appropriate SCAN option from the File pulldown menu. You can scan either selected modules, or simply scan all modules.
After scanning, any error messages are displayed in the scan dialog which automatically appears when you invoke the function. You want to make sure your 'make' pass was successful before proceeding.
Once you have scanned the code modules and are satisfied with the format of how the documentation will appear according to the template in effect, you are ready to generate the documentation. This is done by executing the Document option from the Session pulldown menu in the Xgeorge main window.
The result is a FrameMaker MIF (Maker Interchange Format) module which you can open with Frame. If you happened to produce the HTML version, then the content of the MIF file may be an HTML file which is viewable using Netscape.
For this review I used a public domain program called flip (downloaded from ftp.x.org). I went through the steps described in this review and produced an HTML document.
This document took all of about a half a second to generate on a SPARC 20, about 3 seconds on a SPARC 2, and about a quarter of a second on an HP I70 server. In short, it was FAST! A lot faster than any human could possibly have done.
This GEORGE is not to be confused with John F. Kennedy Jr.'s new political magazine. All kidding aside, GEORGE is one of the best documentation products I've ever seen. In my opinion it is literally worth its weight in gold, for the amount of time and effort it will save developers and project managers in fully documenting any code. You will be amazed at what you can learn about any program code by simply running it through GEORGE's code analyzer.
Bottom line, I really like this product!
As with any first release product you can expect some room for improvement. For example, I would like to see this product handle more than just C or C++ code. It would be nice to define your own language parser and be able to add it to a list of language choices. This would be handy for documenting other types of source code, such as ADA, COBOL (for the mainframe crowd, remember them?), Tcl, PERL, DTKSH, SMALLTALK, and perhaps even HTML.
Another improvement I would like to see is an even more simplistic approach the user interface, similar to the way many Windows applications now offer, by using Wizards. This is where the application displays a dialog, or series of dialogs, to help guide novice users (or simply as a convenience) through the entire process. (QualSoft note: the wizard interface is part of GEORGE 3.0.) Another nice feature I would have thought would have been included is the ability to drive GEORGE without actually sitting in front of a CRT - in other words, a scripting interface to do several documentation passes on a lot of in-house systems. (QualSoft note: the Departmental Server version of GEORGE supports unattended operation.)
One thing I fully expect to see over the coming year is for the many GUI builder tool vendors to wake up and realize that bundling GEORGE with their own products would make them more attractive, and I also would expect that some of them will even work out a live link interface with GEORGE, the same way they did with ObjectCenter, to produce well program documentation that is a standard part of the builder tool's output.
Ahhh, but this is the future. As for now, I think that even in its present state GEORGE, though some may think the pricing is high, is a bargain and that if you're serious about your software development projects, you should put GEORGE on your must have list.
Steve Mikes
Editor of The X Advisor and Cross Platform Solutions magazines. Steven is a hands-on X developer and industry consultant, has taught X, Motif, and MS Windows programming to numerous companies all over the world, and is the author of several books on UNIX and X. He is also the former Editor of The X Journal and Cross Platform Strategies. His email address is smikes@unx.com